Department of Electrical Engineering and Computer Science
The George Washington University Washington, DC 20052
(202) 994-5253 (voice)
(202) 994-5296 (fax)
mfeldman@seas.gwu.edu (Internet)
This project was sponsored by The George Washington University, and in part by the United States Advanced Research Projects Agency (ARPA) under contract #FY3592-93-10234, administered by Phillips Laboratory, Kirtland AFB, NM 87117-5776.
Copyright (C) 1994,1995 Manuel A. Perez and Michael Bliss Feldman
This program is free software; you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
ABOUT THE GW-Ada/Ed-Mac DEVELOPMENT ENVIRONMENT
===============================================
GW-Ada/Ed-Mac is a development environment built around the New York University (NYU) AdaEd compiler/interpreter. It allows the editing, compiling, binding and execution of Ada 83 programs. GW-Ada/Ed-Mac was supervised by Prof. Michael B. Feldman. Manuel A. Perez, a GWU doctoral student in Computer Science, is responsible for the Macintosh version, including the editor and developer shell.
The latest releases (post 1.1) are due mostly to Fabrizio Oddone <fab@kagi.com>, a known shareware developer in Italy. Fabrizio re-compiled the compiler/binder components using MetroWerks CodeWarrior 7, and implemented several source optimizations: compilation is speeded up by a factor of anywhere from 8 to greater than 20. Further, Fabrizio's work includes a version that will run natively on PowerMacs (including the new ones with 603 and 604 processors), and a version for machines with a 68000 processor running System 7, too. Lastly, Fabrizio let the compilers reduce their memory footprint by cleverly using either their own application memory or temporary memory.
This version incorporates some bug fixes made by Charles Lindsey.
NYU's original README file is included in the distribution, for your information.
ACQUIRING AND INSTALLING GW-Ada/Ed-Mac FROM AN FTP ARCHIVE
Any Mac with System 7 and at least 2.5Mb of RAM. You should have around 10Mb free space on your hard disk, too. GW-Ada/Ed-Mac will NOT run under System 6.
How to decode
-------------
The files you get from an Internet archive are BinHex-ed Stuffit archives. Once you've downloaded the files to your Mac, you need to use the StuffIt Expander utility program to decode and decompress them. StuffIt Expander is a free program that you can pick up from any Mac archive or user group.
The folder named "GW-Ada/Ed" contains an icon named "GW Ada/Ed". This is a double-clickable application. The other files are not. Do NOT move or otherwise disturb these files! GW-Ada/Ed expects to find those files, and behavior will be unpredictable if you mess with them. The folders GWUDemos, NYUDemos, and Spider contain sets of interesting programs to demonstrate the capabilities of GW-Ada/Ed-Mac and of Ada in general. GWUDemos was produced by GWU, NYUDemos by NYU, and Spider by John Dalbey of California Polytechnic State University at San Luis Obispo.
ELECTRONIC DISCUSSION GROUP
===========================
We are happy to announce the formation of an automated mailing list for discussions about GW-Ada/Ed. We get a lot of repetitive e-mail on this subject, so we decided to make the discussions public. Several of us at GW will be regularly reading and responding to messages from this list.
To use the list, you must first subscribe. Send an e-mail note to listproc@seas.gwu.edu. The subject line must be _empty_; the message should contain the 3 lines
help
help set
subscribe gw-adaed firstname lastname (substitute your own names!)
The first 2 lines will get you help messages indicating how to use the various options listproc provides; the third line subscribes you to the list. This is all automated; our hands do not touch your message.
Once you get an e-mail acknowledgement of your subscription, you can write to the list by sending e-mail to gw-adaed@seas.gwu.edu. In messages to the list, do _not_ leave the subject line empty.
We hope you will spread around the news of the availability of this list. You do _not_ need Usenet news accesss or ftp to join the list; you need only to be able to send and receive Internet e-mail.
We hope you enjoy the list, and using GW-Ada/Ed!
STARTING TO USE GW-Ada/Ed
=========================
This section gives a tutorial on using GW-Ada/Ed.
Starting the GW-Ada/Ed editor
-----------------------------
1. Double-click on the GW Ada icon, which will put you in the editor. This looks and works like a normal Mac text editor. It is not a word processor; it cannot do formatting of text other than font changes. It can work with multiple open windows, supporting cut, copy, and paste in the usual way.
Opening and compiling a program
-------------------------------
2. From the File menu, select Open, then move through the file-selection dialog until you get into the folder GWU Demos.
3. Select first.ada, opening this file into the editor.
4. From the Develop menu, select Compile. You will be prompted to create a user library, or open an existing one. An Ada library is the place where the compiler puts all its compilation results.
5. Click on New Library. A file selection box opens; just click Create. This will put an Ada library folder into your demo source code folder, which is right where we want it to be. Do NOT move this library folder or try to use the files in it.
6. The compiler will translate your program into Ada/Ed "virtual code", and put the results in your Ada library folder. It will then open a window showing a compilation listing file. To get this file off the screen requires you to select another window from the Windows menu, say, first.ada, then select the listing file first.lis from that menu. You can then close the window in the usual Mac way: click in the little box in the upper left corner.
Requiring you to go through this window selection before closing the listing window is a bug in our system; we are working on it.
7. You can eliminate the listing file opening each time you compile, by selecting, from the Develop menu, Compile Options. Click on the radio button marked "only if errors are found". If a compilation results in error messages, the listing opens. Otherwise, the listing is just stored in your current (source) directory.
8. From the Windows menu, select Library. This will give you a window showing all the compilation results so far. Notice the entry for subprogram "first", given as an "active" entry.
Linking ("binding") the program
-------------------------------
9. You now need to link this program. "Binding" is what Ada calls the linking process. From the Develop window, select Bind and follow the arrow to FIRST. Selecting this will invoke the binder.
10. Select the library window, and note that there is a new line in the window, mentioning "binding unit FIRST_idle_task". This means that FIRST is now a bound program, ready to execute.
Executing the program
---------------------
11. From the Develop menu, select Execute, then follow the arrow to FIRST. Selecting this will execute the program. The program prompts you for your name, then greets you by name. After execution, just click in the little box to close the console window.
A file called FIRST.OUTPUT will appear in your current folder. This contains all the output from your program execution. In a later release, we will let you exercise more control over this file. For now, you can just delete it if you don't want to keep it. If you run the program a second time, a new file overwrites the first one, so if you wish to keep the old one, you must rename it.
Shortcuts in the Library window
-------------------------------
12. Click on the line "subprogram FIRST" in the Library window. You will see the little Bind button "light up" at the top of the window. Clicking the Bind button will call up the binder.
13. Now double-click on the same line; it will also cause binding to occur.
14. Clicking on a "binding unit" line will light up the Execute button; double-clicking that line will cause execution of the program. Later, when you have lots of library entries, you will find that clicking or double-clicking on package spec or package body lines will have no effect. This is intentional; it is not sensible to bind or execute a package, only a main program!
TRYING THE OTHER DEMO PROGRAMS
==============================
You are now ready to try the other interesting demo programs in the folder. There is a separate document for this, called GWUDEMOS.DOC, in the demo folder. You can just open this file with the editor and take it from there.
Enjoy!
KNOWN BUGS AND OTHER HINTS
==========================
The original NYU compiler is generally stable and solid but not perfect. It was government-validated several years ago, which means it passed a large set of fairly stringent tests. The original compiler is not being maintained by NYU; their folks are busy developing a brand-new Ada95 true compiler to be distributed as part of the GNU language system. At GW, we are developing the shell and other Ada goodies, but we are not likely to be able to fix bugs in NYU's original code. You can certainly learn a lot about Ada, and, we hope, have a lot of fun, using this system, but it will sometimes fail you. If it does, we're sorry, but that's a part of life in the free-software world. Here are some of the things we know are wrong; as you can see, we will be able to fix (only) some of them.
The listing file problem was mentioned above
--------------------------------------------
Long-running programs may not run for a long time
-------------------------------------------------
they may crash sooner, usually on an out-of-memory condition. We think this is due to "memory leakage" in the Ada/Ed system; what is happening is that you are eventually running out of memory. We are working on this problem; it has not been as serious in the Unix and DOS versions of Ada/Ed, so we think it is connected to the memory management we had to figure out when we ported Ada/Ed to the Mac. One way to avoid out-of-memory conditions is to limit your use of dynamic string concatenations; Ada/Ed is known to be rather leaky on these.
Source files are limited to 32K
-------------------------------
An Ada file larger than this is probably poorly designed and should be split and restructured into smaller files. Be patient.
For those who are interested in Ada tasking
-------------------------------------------
Ada/Ed supports tasking quite well, and provides both run-till-blocked and round-robin (time-sliced) task scheduling. We have not yet supported a user choice on the Execute Options menu (we forgot!), but provided a means to make the choice. The GW-Ada/Ed folder, as distributed, should contain a text file called QuantumSize, with a single small positive integer (8) in it. The interpreter will check for the existence of this file. If the file exists, round-robin scheduling is enabled and the integer is used as the quantum size, i.e., the number of virtual-code instructions executed per slice. If round-robin scheduling seems to be behaving strangely, you can disable it and revert to run-till-blocked scheduling by simply renaming the QuantumSize file. Don't delete it; you may want it back later.
Generics limitation
-------------------
Keep in mind that the biggest Ada limitation in the NYU Ada/Ed compiler is that the specification of a generic package or subprogram must appear in the same file as the corresponding body. This was a limitation of several early Ada compilers. Ada/Ed-C was developed originally in 1987. We cannot fix this limitation; it is not terribly bothersome but you do have to remember it in developing generics.
Internal Error
--------------
Occasionally the compiler, especially the first pass, adafront, will quit and give a message referring to an "internal error". If this happens, it means you've stumbled into a bug in the original NYU compiler, which is generally stable and solid but not perfect. Generally, your program is incorrect and confused the translator; you will usually get a listing file to examine the errors. Sometimes even a correct program will cause an internal error. Get in touch with us; send us the Ada source file that caused the crash. We do not have much time or funding to fix NYU's bugs, but we will try. We make no promises, though.
Error Type #11 on Power Macs
----------------------------
Some users reported spurious errors of this kind while running on Power Macs.
This is a generic error that may be triggered by a variety of factors, not necessarily by a bug in the compiler. Before contacting us, you should attempt to cure the problem yourself following the advice below.
The note is by Brian Bechtel <blob@apple.com>, Apple Developer Technical Support (DTS)
<http://dev.info.apple.com/technotes/tn1011.html>
Excerpt from the Apple technote: [bracketed text is by Fab :-) ]
[Text is quoted without permission - I hope this is no problem, or that any Apple lawyer won’t read this far.]
Here are some user-level suggestions recommended by Apple for unexplained Type 11 or No FPU installed errors:
1. Upgrade your hard disk driver(s) to the latest version available. There are some known problems between SCSI Manager 4.3 and some SCSI disk drivers. Starting with System 7.5, the SCSI Manager 4.3 is installed on all Macintosh Quadras and Power Macintosh computers. There are some known programming problems in some older third-party disk drivers.
[Latest as I am writing this: SCSI Manager 4.3.1 and Apple HD SC Setup 7.3.5]
2. Upgrade to the latest System Software appropriate for your system. Several significant bug fixes in system updates should reduce the number of Type 11 and No FPU Installed errors you encounter.
3. Do a clean install of your System Software. Use the Extensions Manager control panel to determine if any additional control panels or extensions are conflicting with your system software.
[Apple Menu Options, even the latest 1.0.2, is buggy and should not be used IMHO. For one thing, it patches the Resource Manager using the old-fashioned way, so if one has the native Resource Manager (System 7.5.2 or later), the speed advantage is lost since the patches are 680x0 only. This was told me by Alessandro Levi Montalcini who witnessed it.]
[Those on the Internet can browse The Complete Conflict Compendium at:
<http://www.islandnet.com/~quill/c3data.html>
I never checked this out, so this is not an endorsement or recommendation.]
4. Some Type 11 errors may result from corrupted PRAM. Unfortunately, most of extended PRAM is undocumented. (See Inside Macintosh:Operating System Utilites, chapter 7, Parameter RAM Utilities, for what details are documented.) You can restore your default PRAM values by holding down Command-Option-P-R at system startup time.
5. Zap your PRAM by holding down Command-Option-P-R at boot time, or by using a shareware utility such as TechTool.
6. Make sure you are not using composite RAM in a Power Macintosh. Memory specifications are in the developer hardware notes for each computer.
Bug reporting
-------------
If you find bugs in the GW part of the system, namely the editor and "shell", please report them to us, preferably by electronic mail. We will try to fix the bugs or at least suggest a workaround.
